

/*-------------------------------------------------------------------------
 *
 * libpq-be.h
 *	  此文件包含由postmaster在客户端身份验证过程中使用的结构和外部变量的定义。
 *
 *	  请注意，这是后端内部的内容，且不向客户端导出。
 *	  需要对客户端可见的结构在pqcomm.h中。
 *
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * src/include/libpq/libpq-be.h
 *
 *-------------------------------------------------------------------------
 */
#ifndef LIBPQ_BE_H
#define LIBPQ_BE_H

#include <sys/time.h>
#ifdef USE_OPENSSL
#include <openssl/ssl.h>
#include <openssl/err.h>
#endif
#ifdef HAVE_NETINET_TCP_H
#include <netinet/tcp.h>
#endif

#ifdef ENABLE_GSS
#if defined(HAVE_GSSAPI_H)
#include <gssapi.h>
#else
#include <gssapi/gssapi.h>
#endif							/* HAVE_GSSAPI_H */
/*
 * GSSAPI 导入的头文件会在 win32 的全局命名空间中设置很多东西，
 * 这与 msvc 的构建不匹配。它给出了一堆我们忽略的编译警告，
 * 但也定义了一个根本不存在的符号。再次取消定义。
 */
#ifdef _MSC_VER
#undef HAVE_GETADDRINFO
#endif
#endif							/* ENABLE_GSS */

#ifdef ENABLE_SSPI
#define SECURITY_WIN32
#if defined(WIN32) && !defined(_MSC_VER)
#include <ntsecapi.h>
#endif
#include <security.h>
#undef SECURITY_WIN32

#ifndef ENABLE_GSS
/*
 * 定义与 Unix 上的 GSSAPI 兼容的假结构。
 */
typedef struct
{
	void	   *value;
	int			length;
} gss_buffer_desc;
#endif
#endif							/* ENABLE_SSPI */

#include "datatype/timestamp.h"
#include "libpq/hba.h"
#include "libpq/pqcomm.h"


typedef enum CAC_state
{
	CAC_OK,
	CAC_STARTUP,
	CAC_SHUTDOWN,
	CAC_RECOVERY,
	CAC_NOTCONSISTENT,
	CAC_TOOMANY
} CAC_state;


/*
 * GSSAPI 特定的状态信息
 */
#if defined(ENABLE_GSS) | defined(ENABLE_SSPI)
typedef struct
{
	gss_buffer_desc outbuf;		/* GSSAPI 输出令牌缓冲区 */
#ifdef ENABLE_GSS
	gss_cred_id_t cred;			/* GSSAPI 连接凭证 */
	gss_ctx_id_t ctx;			/* GSSAPI 连接上下文 */
	gss_name_t	name;			/* GSSAPI 客户端名称 */
	char	   *princ;			/* 用于身份验证的 GSSAPI 主体，如果未使用 GSSAPI 身份验证则为 NULL */
	bool		auth;			/* 使用的 GSSAPI 身份验证 */
	bool		enc;			/* 使用的 GSSAPI 加密 */
#endif
} pg_gssinfo;
#endif

/*
 * 这用于后端与前端的通信。它包含在后端运行之前进行此通信所需的所有状态信息。
 * Port 结构保存在 malloc 的内存中，并且在后端运行时仍然可用（见 MyProcPort）。
 * 它指向的数据也必须是 malloc 的，或者在 TopMemoryContext 中 palloc 的，
 * 以便它可以在 PostgresMain 执行期间存活！
 *
 * 如果我们在连接设置期间成功反向查找客户端的 IP 地址，则设置 remote_hostname。
 * remote_hostname_resolv 跟踪主机名验证的状态：
 *	+1 = remote_hostname 已知能解析为客户端的 IP 地址
 *	-1 = remote_hostname 已知无法解析为客户端的 IP 地址
 *	 0 = 我们尚未进行正向 DNS 查找
 *	-2 = 名称解析发生错误
 * 如果客户端 IP 地址的反向查找失败，则 remote_hostname 将保持为 NULL，同时 remote_hostname_resolv 设置为 -2。
 * 如果反向查找成功但正向查找失败，remote_hostname_resolv 也设置为 -2
 * （这种情况是可区分的，因为 remote_hostname 不是 NULL）。在任何 -2 的情况下，remote_hostname_errcode
 * 保存查找返回代码以供后续可能使用 gai_strerror。
 */

typedef struct Port
{
	pgsocket	sock;			/* 文件描述符 */
	bool		noblock;		/* 套接字是否处于非阻塞模式？ */
	ProtocolVersion proto;		/* FE/BE 协议版本 */
	SockAddr	laddr;			/* 本地地址（后端管理器） */
	SockAddr	raddr;			/* 远程地址（客户端） */
	char	   *remote_host;	/* 远程主机的名称（或 IP 地址） */
	char	   *remote_hostname;	/* 远程主机的名称（非 IP 地址），如果可用 */
	int			remote_hostname_resolv; /* 详见上文 */
	int			remote_hostname_errcode;	/* 详见上文 */
	char	   *remote_port;	/* 远程端口的文本表示 */
	CAC_state	canAcceptConnections;	/* postmaster connection status */

	/*
	 * 需要从启动包中保存并传递到后端执行的信息。“char *”字段如果未设置则为NULL。
	 * guc_options指向一个交替的选项名称和值的列表。
	 */
	char	   *database_name;
	char	   *user_name;
	char	   *cmdline_options;
	List	   *guc_options;

	/*
	 * 启动包应用程序名称，仅在此用于“连接授权”日志消息。我们在启动后不应使用这个，而是应该使用GUC，因为应用程序可以随后更改它。
	 */
	char	   *application_name;

	/*
	 * 在身份验证周期中需要保持的信息。
	 */
	HbaLine    *hba;

	/*
	 * 经过身份验证的身份。该标识符的含义取决于hba->auth_method；它是用户在身份验证周期内展示的身份（如果有的话），在他们被分配数据库角色之前。
	 * （它实际上是pg_ident用户映射的“系统用户名称”——虽然使用的确切字符串可能不同，具体取决于pg_hba选项。）
	 *
	 * 如果用户实际上尚未通过身份验证，authn_id为NULL，例如如果使用“trust”身份验证方法。
	 */
	const char *authn_id;

	/*
	 * TCP保持活动和用户超时设置。
	 *
	 * 默认值为0，如果是AF_UNIX或尚未知；如果是AF_UNIX或使用默认值，则当前值为0。 另外，默认值中的-1表示我们无法找出默认值（getsockopt失败）。
	 */
	int			default_keepalives_idle;
	int			default_keepalives_interval;
	int			default_keepalives_count;
	int			default_tcp_user_timeout;
	int			keepalives_idle;
	int			keepalives_interval;
	int			keepalives_count;
	int			tcp_user_timeout;

	/*
	 * GSSAPI结构。
	 */
#if defined(ENABLE_GSS) || defined(ENABLE_SSPI)

	/*
	 * 如果此连接支持并使用GSSAPI，存储GSSAPI信息。即使未编译GSSAPI，也存储一个NULL指针以保持结构偏移相同（以确保扩展ABI兼容性）。
	 */
	pg_gssinfo *gss;
#else
	void	   *gss;
#endif

	/*
	 * SSL结构。
	 */
	bool		ssl_in_use;
	char	   *peer_cn;
	char	   *peer_dn;
	bool		peer_cert_valid;

	/*
	 * OpenSSL结构。（将这些放在最后，以便在启用SSL的情况下，其他字段的位置保持不变。）
	 */
#ifdef USE_OPENSSL
	SSL		   *ssl;
	X509	   *peer;
#endif
} Port;

#ifdef USE_SSL
/*
 * 硬编码的DH参数，用于临时DH密钥生成。（有关EDH的更多详细信息，请参阅README.SSL。）
 *
 * 这是来自RFC 3526的2048位DH参数。质数的生成在RFC 2412附录E中有所规定，文中还讨论了生成器的设计选择。 注意，当使用OpenSSL加载时，这会导致DH_check()在DH_NOT_SUITABLE_GENERATOR上失败，其中泄漏一个位是首选。
 */
#define FILE_DH2048 \
"-----BEGIN DH PARAMETERS-----\n\
MIIBCAKCAQEA///////////JD9qiIWjCNMTGYouA3BzRKQJOCIpnzHQCC76mOxOb\n\
IlFKCHmONATd75UZs806QxswKwpt8l8UN0/hNW1tUcJF5IW1dmJefsb0TELppjft\n\
awv/XLb0Brft7jhr+1qJn6WunyQRfEsf5kkoZlHs5Fs9wgB8uKFjvwWY2kg2HFXT\n\
mmkWP6j9JM9fg2VdI9yjrZYcYvNWIIVSu57VKQdwlpZtZww1Tkq8mATxdGwIyhgh\n\
fDKQXkYuNs474553LBgOhgObJ4Oi7Aeij7XFXfBvTFLJ3ivL9pVYFxg5lUl86pVq\n\
5RXSJhiY+gUQFXKOWoqsqmj//////////wIBAg==\n\
-----END DH PARAMETERS-----\n"

/*
 * 这些函数由特定于每个SSL实现的粘合代码实现（例如：be-secure-openssl.c）。
 */

/*
 * 初始化全局SSL上下文。
 *
 * 如果isServerStart为true，则将任何错误报告为FATAL（以便我们不返回）。
 * 否则，记录错误为LOG级别，返回-1以表示出现问题，保留旧的SSL状态（如果有）。返回0表示正常。
 */
extern int	be_tls_init(bool isServerStart);

/*
 * 销毁全局SSL上下文（如果有）。
 */
extern void be_tls_destroy(void);

/*
 * 尝试协商SSL连接。
 */
extern int	be_tls_open_server(Port *port);

/*
 * 关闭SSL连接。
 */
extern void be_tls_close(Port *port);

/*
 * 从安全连接中读取数据。
 */
extern ssize_t be_tls_read(Port *port, void *ptr, size_t len, int *waitfor);

/*
 * 向安全连接写入数据。
 */
extern ssize_t be_tls_write(Port *port, void *ptr, size_t len, int *waitfor);

/*
 * 返回有关 SSL 连接的信息。
 */
extern int	be_tls_get_cipher_bits(Port *port);
extern const char *be_tls_get_version(Port *port);
extern const char *be_tls_get_cipher(Port *port);
extern void be_tls_get_peer_subject_name(Port *port, char *ptr, size_t len);
extern void be_tls_get_peer_issuer_name(Port *port, char *ptr, size_t len);
extern void be_tls_get_peer_serial(Port *port, char *ptr, size_t len);

/*
 * 获取 SCRAM 通道绑定类型 tls-server-end-point 的服务器证书哈希。
 *
 * 结果是一个 palloc 的服务器证书哈希及其大小，如果没有可用的证书则为 NULL。
 *
 * 旧版本的 OpenSSL 不支持此功能，因为它们没有 X509_get_signature_nid() 函数。
 */
#if defined(USE_OPENSSL) && (defined(HAVE_X509_GET_SIGNATURE_NID) || defined(HAVE_X509_GET_SIGNATURE_INFO))
#define HAVE_BE_TLS_GET_CERTIFICATE_HASH
extern char *be_tls_get_certificate_hash(Port *port, size_t *len);
#endif

/* SSL 的初始化钩子，默认情况下如果合适会设置密码回调 */
#ifdef USE_OPENSSL
typedef void (*openssl_tls_init_hook_typ) (SSL_CTX *context, bool isServerStart);
extern PGDLLIMPORT openssl_tls_init_hook_typ openssl_tls_init_hook;
#endif

#endif							/* USE_SSL */

#ifdef ENABLE_GSS
/*
 * 返回有关 GSSAPI 认证连接的信息
 */
extern bool be_gssapi_get_auth(Port *port);
extern bool be_gssapi_get_enc(Port *port);
extern const char *be_gssapi_get_princ(Port *port);

/* 读取和写入 GSSAPI 加密连接。 */
extern ssize_t be_gssapi_read(Port *port, void *ptr, size_t len);
extern ssize_t be_gssapi_write(Port *port, void *ptr, size_t len);
#endif							/* ENABLE_GSS */

extern PGDLLIMPORT ProtocolVersion FrontendProtocol;

/* TCP保持活跃配置。 在AF_UNIX套接字上这些是无操作。 */

extern int	pq_getkeepalivesidle(Port *port);
extern int	pq_getkeepalivesinterval(Port *port);
extern int	pq_getkeepalivescount(Port *port);
extern int	pq_gettcpusertimeout(Port *port);

extern int	pq_setkeepalivesidle(int idle, Port *port);
extern int	pq_setkeepalivesinterval(int interval, Port *port);
extern int	pq_setkeepalivescount(int count, Port *port);
extern int	pq_settcpusertimeout(int timeout, Port *port);

#endif							/* LIBPQ_BE_H */
